---
title: "Labels"
description: "Organize your memory with workspace-scoped labels"
---

## Overview

Labels are CORE's flexible tagging system for organizing episodes, sessions, and documents within your workspace. Think of them as project tags or categories that help you filter and find related memories quickly.

Unlike traditional hierarchical folders, labels use a flat, Linear-style organization that lets you apply multiple tags to any piece of content, making it easy to organize information across different contexts and projects.

## What Are Labels?

Labels are workspace-unique tags that you can assign to:
- **Episodes**: Individual conversations and interactions
- **Sessions**: Related groups of conversations
- **Documents**: Files and content you've ingested

Each label has:
- **Name**: A unique identifier within your workspace (max 100 characters)
- **Description**: Optional details about what the label represents
- **Color**: Visual identifier for quick recognition
- **Workspace Scope**: Labels are unique per workspace, not global

## Key Characteristics

### Workspace-Scoped
Labels are scoped to your workspace, meaning:
- Each workspace has its own set of labels
- Label names must be unique within a workspace
- Different workspaces can have labels with the same name
- You can't share labels across workspaces

### Multiple Labels per Item
You can assign multiple labels to any episode:
- Episodes have a `labelIds` array field
- No limit on the number of labels per episode
- Filter searches by one or multiple labels
- Labels don't nest or form hierarchies

## How Episodes Use Labels

When you ingest content or have conversations, episodes can be tagged with labels:

```typescript
{
  id: "episode-uuid",
  content: "Conversation about authentication...",
  labelIds: ["label-uuid-1", "label-uuid-2"],
  isFavorite: false,
  folders: [] // User.folders for personal organization
}
```

## Creating and Managing Labels

### Via Web Interface
1. Navigate to **Settings → Labels**
2. Click **"Create Label"**
3. Enter name, optional description, and choose a color
4. Labels appear in your workspace immediately

### Via API
List all labels in your workspace:

```bash
GET /api/v1/labels
```

See the [API Reference](/api-reference) for details.


## Using Labels in Search

Labels provide powerful filtering capabilities across all search methods:

### Basic Search with Labels
```typescript
memory_search({
  query: "API design decisions",
  labelIds: ["project-taskmaster-uuid"]
})
```

### Multiple Label Filtering
Search across multiple labels to find related content:
```typescript
memory_search({
  query: "security vulnerabilities",
  labelIds: ["label-auth-uuid", "label-api-uuid"]
})
```

### Recent Work by Label
Combine labels with time filters:
```typescript
memory_search({
  query: "recent progress",
  labelIds: ["label-project-uuid"],
  startTime: "2025-01-01T00:00:00Z",
  sortBy: "recency"
})
```

## Label-Based Search Architecture

When you filter by labels, CORE's search system:

1. **BM25 Search**: Filters episodes by `labelIds` before scoring
2. **Vector Search**: Applies label filter to episode embeddings
3. **Episode Graph Search**: Constrains graph traversal to labeled episodes
4. **BFS Search**: Limits entity exploration to episodes with matching labels

This ensures that label filtering is efficient and works consistently across all search methods.

## API Endpoints for Label Management

| **Endpoint**                | **Method** | **Description**                    |
| --------------------------- | ---------- | ---------------------------------- |
| `/api/v1/labels`            | GET        | List all labels in workspace       |

Additional label management operations (create, update, delete) are available through the web interface.

## MCP Integration with Labels

CORE's MCP server exposes memory tools that support label filtering:

### Available Tools
- `memory_search`: Search with optional `labelIds` array
- `memory_ingest`: Store conversations with `labelIds`
- `memory_get_labels`: List all workspace labels
- `memory_get_document`: Retrieve specific documents

## Best Practices

### Label Naming
- Use clear, descriptive names (e.g., "TaskMaster Project", "Authentication")
- Keep names concise but meaningful
- Use consistent naming conventions across your workspace

### Label Organization
- Create labels for projects, topics, or contexts
- Don't over-label - use 2-4 labels per episode typically
- Use favorites for truly important items rather than creating "Important" labels

## Examples

### Organizing a Multi-Project Workspace
```
Labels:
- "Project: TaskMaster" (color: blue)
- "Project: CORE Features" (color: green)
- "Client: Acme Corp" (color: purple)
- "Topic: Authentication" (color: red)
- "Topic: Performance" (color: orange)
```

